package com.tianji.learning.service;

import com.tianji.common.domain.dto.PageDTO;
import com.tianji.learning.domain.dto.QuestionFormDTO;
import com.tianji.learning.domain.po.InteractionQuestion;
import com.baomidou.mybatisplus.extension.service.IService;
import com.tianji.learning.domain.query.QuestionAdminPageQuery;
import com.tianji.learning.domain.query.QuestionPageQuery;
import com.tianji.learning.domain.vo.QuestionAdminVO;
import com.tianji.learning.domain.vo.QuestionVO;

/**
 * <p>
 * 互动提问的问题表 服务类
 * </p>
 *
 * @author zr
 * @since 2024-07-16
 */
public interface IInteractionQuestionService extends IService<InteractionQuestion> {

    /**
     * 保存问题信息。
     * <p>
     * 该方法接收一个QuestionFormDTO对象作为参数，该对象包含了用户提交的问题的所有相关信息。
     *
     * @param questionDTO 包含问题信息的数据传输对象。这个对象应该包含了问题的所有必要属性，
     *                    如问题的标题、内容、提交者等信息。
     */
    void saveQuestion(QuestionFormDTO questionDTO);

    /**
     * 更新问题的信息。
     * <p>
     * 通过此方法，可以对数据库中已存在的问题进行修改。修改的内容由QuestionFormDTO对象携带，
     * 包括问题的各个属性，如问题描述、答案等。
     *
     * @param id          问题的唯一标识符，用于在数据库中定位到需要更新的问题。
     * @param questionDTO 包含更新后问题信息的数据传输对象，通过此对象的属性值来更新数据库中的问题。
     */
    void updateQuestion(Long id, QuestionFormDTO questionDTO);

    /**
     * 根据查询条件获取问题分页数据。
     * <p>
     * 该方法通过QuestionPageQuery参数来检索问题的分页信息。它封装了对问题数据的查询条件，
     * 并返回包含问题数据的分页DTO对象。
     *
     * @param query 查询条件对象，包含分页和过滤条件。
     * @return PageDTO<QuestionVO> 包含查询结果的分页数据传输对象。
     */
    PageDTO<QuestionVO> queryQuestionPage(QuestionPageQuery query);

    /**
     * 根据问题ID查询问题详情。
     * <p>
     * 本方法通过调用数据库查询接口，使用问题的唯一标识ID来获取特定问题的详细信息。
     * 这些信息可能包括问题的标题、描述、创建时间等。该方法旨在为前端提供一个问题查询接口，
     * 以便用户可以通过问题ID来查看问题的详细内容。
     *
     * @param id 问题的唯一标识ID，用于在数据库中定位特定问题。
     * @return 返回查询到的问题详情，封装在QuestionVO对象中。如果未找到对应问题，则返回null。
     */
    QuestionVO queryQuestionById(Long id);

    /**
     * 查询问题管理页面的分页信息。
     * <p>
     * 该方法通过QuestionAdminPageQuery查询条件来获取问题管理页面的分页数据。返回PageDTO<QuestionAdminVO>对象，
     * 包含分页信息和问题的详细管理视图（QuestionAdminVO）。
     *
     * @param query 查询条件对象，包含分页信息和过滤条件。
     * @return 返回一个PageDTO<QuestionAdminVO>对象，其中包含查询结果的分页信息和问题详情。
     */
    PageDTO<QuestionAdminVO> queryQuestionPageAdmin(QuestionAdminPageQuery query);

    /**
     * 根据指定的ID删除本账号的问题。
     * <p>
     * 此方法旨在通过提供的ID来删除数据库中对应的问题记录。
     *
     * @param id 要删除的实体的唯一标识符。这个参数是必需的，且不能为null，
     *           它被用于准确地定位到要删除的实体。
     */
    void deleteById(Long id);

    /**
     * 根据给定的ID和隐藏状态来隐藏问题。
     * 此方法用于更新问题的隐藏状态，可以通过指定问题的ID和一个新的隐藏状态来实现。
     * 如果hidden为true，则将问题设置为隐藏；如果为false，则将问题设置为可见。
     *
     * @param id     问题的唯一标识符。用于确定要更新哪个问题的状态。
     * @param hidden 一个布尔值，指示问题的新隐藏状态。true表示隐藏，false表示可见。
     */
    void hiddenQuestion(Long id, Boolean hidden);

    /**
     * 根据问题ID查询问题的管理员视图对象。
     * <p>
     * 此方法用于管理员后台，通过问题的唯一标识符ID，从数据库中检索该问题的详细信息。
     * 返回的问题信息是专门为管理员设计的视图对象，包含比普通用户视图更多的管理相关字段。
     *
     * @param id 问题的唯一标识符，类型为长整型。
     * @return 返回管理员视图下的问题对象，如果找不到对应问题，则可能返回null。
     */
    QuestionAdminVO queryQuestionByIdAdmin(Long id);
}
